home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / C / LIB / DESK / CORE / Desk / h_doc / Msgs < prev    next >
Text File  |  1996-05-21  |  5KB  |  123 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Msgs.h
  12.     Author:  Copyright © 1992, 1993 Jason Williams
  13.     Version: 1.01 (04 Aug 1993)
  14.     Purpose: MessageTrans-like message handling functions.
  15.              (If you want MessageTrans, use the SWI interface, if you want
  16.              high-level message handling, use this code...)
  17. */
  18.  
  19. #ifndef __Desk_Msgs_h
  20. #define __Desk_Msgs_h
  21.  
  22.  
  23. #ifdef __cplusplus
  24. extern "C" {
  25. #endif
  26.  
  27.  
  28. #ifndef __Desk_Core_h
  29. #include "Desk.Core.h"
  30. #endif
  31.  
  32. extern Desk_bool Desk_Msgs_Lookup(const char *tag, char *result, int maxlength);
  33. /*  Looks up the tag in the current message list, and copies the appropriate
  34.  *  message into result if found. (no more than maxlength characters will
  35.  *  be copied, so you can copy directly into icon indirected text, etc.
  36.  *  REMEMBER that arrays start at 0, so if you have "char result[12]", use
  37.  *  Desk_Msgs_Lookup(tag, result, 11))
  38.  *
  39.  *  The tag string should be of the form:
  40.  *    "group.tag:default"  or  "group.tag"
  41.  *
  42.  *  The message found will be searched for <> includes. If any are found,
  43.  *  Desk_Msgs_Lookup() will be recursively invoked in order to compile
  44.  *  the final string. Note that circular references are not detected,
  45.  *  and will cause stack-chewing recursion until all memory is eaten up,
  46.  *  at which point the recursion (and all life as it we know it) will stop.
  47.  *  However, it will stop when your destination buffer is full, so infinite
  48.  *  recursion will only occur if your included string is empty except for
  49.  *  including itself.
  50.  *
  51.  *  Remember also that more memory than is immediately obvious will
  52.  *  be needed for messages which include others. However, everything will
  53.  *  be truncated if necessary at "maxlength" characters.
  54.  *
  55.  *  NOTE: leading spaces are NOT removed by this call - you MUST use
  56.  *        a compact, space-free format in your program (though you can use
  57.  *        spaces for readability of your messages files)
  58.  *        [This saves code size in this function, as well as forcing you to
  59.  *         not waste space in your executable]
  60.  *
  61.  *  -If the message for group.tag is not found, then default is returned
  62.  *   (if no default, then the null string is returned - result[0] == '\0')
  63.  *
  64.  *  -If the message is found in the message list, Desk_bool_TRUE is returned
  65.  *  -If the default has to be used, Desk_bool_TRUE is returned
  66.  *  Otherwise Desk_bool_FALSE is returned, and result[0] == '\0'
  67.  *
  68.  *  (Thus, if you get (Desk_Msgs_Lookup(...) == Desk_bool_FALSE) then you have no valid
  69.  *  text to use. (Acorn's msgs returns the tag, which is very annoying
  70.  *  when you don't want tags appearing in your interface if anything goes
  71.  *  wrong)
  72.  */
  73.  
  74.  
  75. extern void Desk_Msgs_printf(char *result, const char *formattag, ...);
  76. /*  Equivalent to sprintf(), but the "formattag" string is NOT a format
  77.  *  string, but rather a Msgs tag which is given to Desk_Msgs_Lookup in order
  78.  *  to generate a format string for subsequent use.
  79.  */
  80.  
  81.  
  82. extern Desk_bool Desk_Msgs_LoadFile(const char *leafname);
  83. /*  Merges the given messages file into the current list of messages
  84.  *  (Uses Resource to supply the pathname)
  85.  *  Messages with the same group.msg tag will be overwritten by the
  86.  *  new messages coming in from the file.
  87.  *
  88.  *  Expects lines of the form:
  89.  *    group.msg: message text continuing to newline
  90.  *  Leading spaces are stripped
  91.  *
  92.  *  NOTE that the last message from the file may be lost unless there are
  93.  *  a couple of return characters on the end of the file.
  94.  */
  95.  
  96.  
  97. extern void Desk_Msgs_DropGroup(const char *grouptag);
  98. /*  Drops (deletes) a message group from memory
  99.  *  This is useful for regaining memory when a set of messages is no longer
  100.  *  needed (e.g. Help messages can be discarded when a user turns off help)
  101.  *
  102.  *  To get discarded messages back, you must re-call Desk_Msgs_LoadFile for the
  103.  *  appropriate messages file.
  104.  */
  105.  
  106.  
  107. extern void Desk_Msgs_Report(int errnum, const char *tag, ...);
  108. /* Reports an error for the message specified by tag.
  109.  * You can also pass variable parameters for substitution.
  110.  * (See Error.h - Desk_Error_Report for the non-messagetrans'd version of this)
  111.  */
  112.  
  113.  
  114. extern void Desk_Msgs_ReportFatal(int errnum, const char *tag, ...);
  115. /* As for Desk_Msgs_Report but calls Desk_Error_ReportFatal
  116.  */
  117.  
  118. #ifdef __cplusplus
  119. }
  120. #endif
  121.  
  122. #endif
  123.